perm filename SPOOL.REG[UP,DOC]1 blob
sn#002749 filedate 1972-10-06 generic text, type T, neo UTF8
SPOOLER SYSTEM DOCUMENTATION: SPOOL, PRINTR, SPOOLQ and UNSPOOL.
Spooler for line printer listings
R. E. Gorin 15 Feb 1971
Revision #5. 18 July 1972
NOTICE:
The program "SPOOL" reported in this document is now in
temporary form. I expect that it will change substantially within
the next few weeks. The changes that will be made will allow a
wider range of services to users and more mnemonic switch names.
Revision 5 of this document reflects the features of the "new
spooler"
REG
Spooling provides a method of producing line printer listings
of files without the usual disadvantage of tying up a users job while
the listing is actually being done.
To take advantage of the spooler, a user must create commands
for it. A command is generally the name and location of a file to
list. These spooler commands are created by the system level command
"SPOOL."
This file documents the entire spooler system:
SPOOL - Accept commands to spool files
PRINTR - The actual listing program.
SPOOLQ - Spooler status report program
UNSPOOL - Deletes spooled requests. Modifies PRINTR behavior
SPSUB - Subroutines to make spooler command files
(These subroutines are documented separately in
SPSUB.REG[UP,DOC].)
Example of Spooling.
The monitor level command:
SPOOL SPOOL.REG[S,DOC]
will cause this file to be listed when the line printer becomes
available. When your listing is completed, you will be notified by
the spooler, which will type a message on your console.
Spooled listings are preceeded by a header page (except
see /A below), used to make it easy to separate different listings.
This header includes the file identifier, the name of the requestor,
and his project- programmer number, the current date and time, and
the date abd time when the file was last written. Programmer
names are read from the file FACT.TXT[SPL,SYS]. Project names (of
which there are few) are read from the file XFACT.TXT[SPL,SYS].
SPOOL Send commands to the spooler.
To have the spooler make a listing the user must tell the
spooler what file(s) to print. This easiest way to tell the spooler
what to do is by the system level command SPOOL. This command
consists of the word SPOOL followed by the name(s) of the file(s) to
be listed. File names are separated by commas. Each file name may
be followed by switches, explained below. The program Spool will
send commands to the spooler. The program SPOOL may also be started
by the command R SPOOL.
Files to be spooled are specified in the conventional way, by
file name, extension, and optionally project-programmer number.
Switches following the file name are allowed. At present these are:
/D DELETE this file after printing. The file protection of this
file must be low enough so that the spooler can delete it.
/N NONUMBERS: List without SOS line numbers.
/O ODD MODE: Init the LPT in mode 101 instead of mode 1.
/P (PIP COMPATIBILITY): Treat the first charater of every line
as a FORTRAN carriage control character.
/B BLANK: Suppress the page-top heading. Headings at the top
of each page will be supplied unless this switch is set.
Note: Files with extension "LST" will be listed without
headings, unless /H is set (see below).
/H HEADING: Print a heading at the top of each page. The
heading includes date,time,file name and page number term.
The page number term is the <SOS page number>- <the number of
lpt pages used so far for this SOS page>.
/A ANONYMOUS: Suppress the two pages of heading that otherwise
precede the actual listing.
/nnR REPEAT: Specify nn copies. See explanation below.
/dE EXTRA LINES: Specify d extra line feeds to be inserted into
the listing after every line feed in the file. The digit d
may be 0, 1, 2 or 3. /0E means single spacing with no form
feeds between pages.
/S Short, that is, narrow, headings. The heading block on the
first two pages will be moved to the left so it will be
centered for 8.5" wide pages.
/U Octal listing. Data will be printed as octal full words.
(Similar to /DUMP in COPY).
/T Suppress "spooling finished" message when listing is done.
/C Turn line feed into '177&'21.
DELAYED LISTINGS
Usually requests for spooled listings will be processed as
rapidly as possible. Under some circumstances this may not be
desired. For example, a long listing impacts the normal operation of
the system by making the line printer unavailable during its
duration. The spooler allows users to delay such listings until a
time of minimum loading (e.g., 0500) when the unavailability of the
line printer is less likely to interfere with other users.
If the construction "<" number ">" appears in a command line
then the number is interpreted as the (24 hour) time of day when the
listing should actually be sent to the line printer. In the example
below, 1730 will be interpreted as 5:30 PM.
Example: SPOOL SYSTEM.LST[S,SYS]<1730>
If the time specified is smaller than the current time, it is
interpreted to mean, "list the file tomorrow at the time specified".
That is, if at 10PM you give the command:
SPOOL BAZ.FAI<400>
then the listing will occur in six hours.
SELECTION OF PAGES TO LIST
You may follow a file name by a list of ranges of pages that
you want listed. The list must be parenthesized. For example:
SPOOL FOO.SAI (1,7,5:8)
will cause page 1, page 7 and pages 5 through 8 inclusive to be
listed.
In octal dump mode, this page range list is used to specify
a word-range to list.
MULTIPLE COPIES OF A FILE
The switch /nnR is accepted by SPOOL. The effect is to
interpret "nn" as a decimal number and to list that many copies of
the file. Multiple copies are spooled as usual, except that the two
pages of heading that normally precede a file (except if the /A
switch is used) are suppressed on the second and subsequent copies of
the file. /R and /0R are equivalent to /1R, which is the default.
The queue discipline of the spooler allows all other users a
chance to use the line printer between every file (or every copy of a
file), so that multiple listing may be broken into two or more piles
of paper, but not broken within a file.
SPOOLQ
SPOOLQ is invoked by the system command SPOOLQ. SPOOLQ reads
the directory of [SPL,SYS] and interprets the contents of the SPL
(spooler command) and TDL (time delay command) files. Essentially,
it displays the queue of files to be printed.
The queue is based on a priority scheme. The priority of a
spool request is determined by
<time in minutes since spool request, +1>/<file size in records>
Requests are processed in the opder of decreasing priority.
Line printer allocation:
The spooler uses the following scheme when it
wants to use the line printer. It uses the DEVUSE uuo to determine
if there is any one in the queue waiting for the LPT, and if there is
such a person, it waits until there is no one waiting for the LPT and
there is no one using the LPT. Once the LPT is initialized by the
spooler, the spooler hangs on to it until either it finishes
processing all command files, or it begins a new listing file and
discovers that some one is queued waiting for the LPT. In either
case, the spooler releases the LPT.
UNSPOOL
UNSPOOL is a monitor level command that invokes the program
SPOOLQ in a strange way:
If you run UNSPOOL it will display all the spooler commands
that you (your PPN) have requested, and it will allow you to delete
any of the command files that it displays. If you delete a command
file that hasn't been seen by the spooler then nothing special
happens since the spooler is not yet aware of the command, so it
won't be missed. If it happens that the spooler is already
processing your commands then the listing in progress will be purged
and a message to that effect will be printed on the partial listing
and on the CTY.
If you log in as SPL,SYS and run Unspool then not only are
you allowed to purge any command file that is either in progress or
pending but you also can change the spooler behavior in the following
ways:
1. You can cause the present listing to be purged.
2. You can cause the present listing to be started over.
3. You can cause the spooler to hold the queue and release
the LPT immediately before starting the next file.
4. You can release the queue from the state induced by
holding it.
5. You can suspend spooling, breaking the listing that is
currently in progress and releasing the LPT. When you
escape from this mode by using the release queue command,
the listing that was broken will be resumed.
The Spooler
The spooler, i.e. the program that actually lists user files
is called PRINTR and runs logged in as [SPL,SYS]. The following
document is copied from the spooler internal documentation. It is
for the purpose of allowing other programmers to interface to the
spooler from their own programs without going through the program
SPOOL. The following information is subject to revision without
prior notice.
Command files to the spooler are written in dump mode, mode
17 on the DSK. The command file must be precisely 200 (octal) words
long. Any name is allowed for the file name; the extension is SPL.
The file shall contain the following data:
Word 0:
This contains the project-programmer number of the person
creating this file.
Word 1:
This word should contain the quantity:
XWD DATE,MTIME
The listing will not be sent to the LPT until the date and
time specified. If the word is zero, or if the date-time specified
is earlier than the present time then the listing will be made as
soon as possible. DATE is in the 12 bit PDP-10 standard form; MTIME
is expressed in minutes past midnight.
Word 2:
The size (in 128 word blocks) of the largest file requested
in this command file. Size of a request is determined by the Lookup.
This size is not affected by multiple copy or page requests.
Word 3:
The filename in sixbit of the file to be listed.
Word 4:
Left half:
The file extension in sixbit.
Right half:
Set bit switches for the following actions:
1 (Bit 35) Delete file after listing.
2 (Bit 34) Fortran carriage control
conversion.
4 (Bit 33) Use LPT mode 101 rather than
mode 1.
10 (Bit 32) Suppress SOS line numbers.
20 (Bit 31) Print page heading.
40 (Bit 30) Suppress the title pages.
(Word 4, continued)
Bits 18-23 are reserved for the repetition count.
If the contents of these six bits are not zero
then they are taken as the total number of copies
to be listed. (0 implies 1 copy). If multiple
copies are requested then they will be listed as
usual, except that the second and subsequent files
will be listed without the two page title page.
Bits 24-25 contain the extra line feed count.
This counts takes on values from 0 to 3. 0
is the default value. The count specifies
the number of extra line feeds to be inserted
following every line feed in the file.
All other bits are reserved for future expansion.
Implied switches:
If Fortran conversion is specified then page headings will
not be done. If a partial listing by pages (see below) is specified
then no fortran conversion will be done.
Word 5: This is zero.
Word 6: This is the ppn of the file owner. If zero then the
disk area specified by word 0 will be used.
Word 7:
If this is zero then the entire file will be listed.
Otherwise, this word and all the words following this word, up to,
and including the next zero word will be interpreted as follows:
If the left half is zero then the right half will be copied
into the left. If the left half is greater than the right
half this word will be ignored. The next word will be
processed. Assuming that the left side is not larger than the
right, the page named in the left side will be listed as will
be all pages following that page, up to and including the
page named on the right. After such a term is processed, the
next term will be processed in the same way. Zero terminates
this processing.
After a zero is seen in the file, the next word is inspected. If it
is not zero then it will be interpreted as a file name, in the same
way that word 3 and subsequent words were interpreted. Processing
of the command file terminates when a zero filename is seen. To be
sure that file processing does stop, a block of 4 zeros is appended
to the internal copy of the command file when it is read.
Spooler Version 2 Operating instructions.
There are three programs pertaining to the spooler.
PRINTR The spooler.
SPOOL The command creation program
SPOOLQ The spooler queue interrogation program
PRINTR
PRINTR runs as a detached job, logged in under the ppn
SPL,SYS. The job is identified by the name *LIST*. Normally, when
idle the spooler will spend most of its time in INTW, interrupt wait.
When it is listing a file, it will be mostly in IOWQ with brief
excursions into RUNQ. If the spooler goes into IOWQ and nothing is
listed, it may be sleeping, waiting for the line printer, which
someone else may have assigned.
The spooler may crash, entering STOP status. If this happens,
chances are that it has grabbed the line printer, rendering the LPT
unavailable to all. To remedy this, do the following:
Attach to the spooler's job.
GET DSK PRINTR
CST
DET
if you wish, you can cause a trace of the spooler's actions to be
typed on the CTY by saying "REE" instead of "CST". Then type ↑C twice
and CCON. (If you type REE and don't CCON then the trace will also
appear on the console that the spooler is attached to.)
SPOOL
SPOOL is used to create command files to the spooler. SPOOL
is kept on the system area. It is accessed either by R SPOOL, or by
the monitor level command SPOOL.
When SPOOL starts it does a NAMEIN to see if it can find a
program named *LIST*. If it can't find such a program, SPOOL will
get a PTY and log in a version of the spooler.
SPOOL creates command files with "SPL" extensions on the
spoolers disk area [SPL,SYS]. These files are read by the spooler,
and they contain the name of the file to be listed. (See
SPOOL.REG[S,DOC] for details.) SPOOL also sends mail to the spooler,
the mail contains no message but is used to bring the spooler out of
INTW.